클로드 코드 완벽 가이드 — 11장 MCP 사용하기 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

11장에서 다루는 내용

• MCP(Model Context Protocol)란? — LLM이 외부 시스템과 소통하는 오픈소스 프로토콜
• MCP 서버 설정하기 — 세 가지 전송 방식(stdio, SSE, HTTP)으로 서버 추가
• MCP 서버 관리하기 — 등록된 서버 목록 확인, 전송 방식별 비교 및 선택 기준

전체 흐름도

[문제 인식: LLM이 대화창 안에만 갇혀 있다]
    |
    v
+--------------------------------------------+
| MCP (Model Context Protocol)               |
| = LLM ↔ 외부 세계를 연결하는 다리           |
| 앤트로픽이 만든 오픈소스 프로토콜             |
| 클라이언트-서버 구조의 개방형 프로토콜        |
+--------------------------------------------+
    |
    v
[MCP 서버 설정하기: claude mcp 명령어]
    |
    +----------+-----------+-----------+
    |          |           |           |
    v          v           v           |
+--------+ +--------+ +--------+     |
| stdio  | | SSE    | | HTTP   |     |
| 로컬   | | 원격   | | 원격   |     |
| 프로세스| | Push   | | 요청/  |     |
| 실행   | | 방식   | | 응답   |     |
+--------+ +--------+ +--------+     |
    |          |           |           |
    v          v           v           |
+--------------------------------------------+
| 추가 방법 2가지                              |
| (1) 커맨드: claude mcp add ...              |
| (2) 직접 편집: .mcp.json 파일 수정           |
+--------------------------------------------+
    |
    v
[claude mcp list 로 연동 확인]
    |
    v
+--------------------------------------------+
| 전송 방식 비교표                              |
| stdio → 로컬, 빠름, 업데이트 수동             |
| SSE   → 원격, 지속연결, 실시간 스트리밍       |
| HTTP  → 원격, 요청/응답, API 연동            |
+--------------------------------------------+

선수 지식 체크리스트

• [ ] 클로드 코드 기본 사용법 (설치, 실행, 슬래시 커맨드)
• [ ] JSON 파일 구조 이해 (key-value, 중첩 객체)
• [ ] 터미널 명령어 기초 (npx, 패키지 실행)
• [ ] 클라이언트-서버 개념 (요청-응답, 프로세스 간 통신)
• [ ] API란 무엇인지 기본 이해

핵심 키워드

11-1 MCP란?

한 줄 요약

MCP(Model Context Protocol)는 LLM이 대화창을 벗어나 외부 데이터베이스, API, 파일 시스템과 직접 상호작용할 수 있게 해주는 앤트로픽의 오픈소스 프로토콜이다.

쉬운 설명 (통역사 비유)

"외국에 혼자 가면 현지인과 대화할 수 없다. 하지만 통역사가 있으면 어떤 사람과도 소통할 수 있다. MCP는 LLM을 위한 '만능 통역사'다. 깃허브, 데이터베이스, 파일 시스템 — 어떤 외부 서비스든 MCP를 통해 LLM이 직접 대화할 수 있게 해준다."

핵심 포인트

1. MCP의 정의: LLM이 데이터베이스, API, 파일 시스템 같은 외부 도구 및 데이터 소스에 접근할 수 있도록 설계된 클라이언트-서버 구조의 개방형 프로토콜
2. 만든 곳: 앤트로픽 (Anthropic) — 클로드를 만든 회사가 직접 설계한 오픈소스 프로토콜
3. 핵심 가치: 클로드 코드가 여러 전문 서버에 동시에 연결하여 확장된 작업을 수행

실무 예제

MCP 없을 때 vs 있을 때 비교:

❌ MCP 없이 (수동 작업)
개발자: "깃허브 이슈 #42 내용 알려줘"
클로드: "저는 깃허브에 접근할 수 없습니다..."
개발자: (브라우저에서 직접 이슈 확인 → 내용 복사 → 클로드에 붙여넣기)

✅ MCP 있을 때 (자동 연동)
개발자: "깃허브 이슈 #42 내용 알려줘"
클로드: (MCP로 깃허브 API 호출 → 이슈 조회)
       "이슈 #42는 로그인 페이지 버그입니다. 관련 PR을 생성할까요?"

MCP로 할 수 있는 일들:

- 깃허브 이슈 생성/조회/관리
- 데이터베이스 스키마 질의 및 데이터 조회
- 원격 서버의 이슈 분석
- API 문서 실시간 참조
- 파일 시스템 접근 및 프로젝트 관리

체크포인트

• [ ] MCP가 Model Context Protocol의 약자라는 것을 기억하는가?
• [ ] MCP가 클라이언트-서버 구조라는 것을 설명할 수 있는가?
• [ ] MCP가 없을 때와 있을 때의 차이를 비유로 설명할 수 있는가?
• [ ] MCP를 통해 클로드가 접근할 수 있는 외부 시스템 3가지 이상을 나열할 수 있는가?

11-2 MCP 서버 설정하기

한 줄 요약

claude mcp 명령어 또는 .mcp.json 파일 직접 편집으로 세 가지 전송 방식(stdio, SSE, HTTP) 중 하나를 선택하여 MCP 서버를 등록한다.

쉬운 설명 (TV 연결 비유)

"TV에 게임기를 연결하는 방법이 여러 가지다. HDMI(직접 꽂기=stdio), 와이파이 캐스트(계속 연결=SSE), 블루투스(필요할 때 연결=HTTP). MCP 서버도 마찬가지로, 상황에 맞는 연결 방식을 골라서 쓴다."

핵심 포인트

1. 세 가지 전송 방식: stdio(로컬), SSE(원격, Push), HTTP(원격, 요청/응답)
2. 서버 추가 방법 2가지: CLI 커맨드(claude mcp add) 또는 .mcp.json 파일 직접 편집
3. 기본값은 stdio: --transport 플래그 없이 추가하면 자동으로 stdio 방식

실무 예제

방법 1: 커맨드로 추가 (stdio)

# 문법
claude mcp add <name> <command> [args...]

# 예제: Context7 MCP 서버 추가
claude mcp add context7 -- npx -y @upstash/context7-mcp

방법 2: .mcp.json에 직접 추가 (stdio)

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp"
      ],
      "env": {}
    }
  }
}

SSE 방식으로 추가:

# 커맨드
claude mcp add --transport sse context7 https://mcp.context7.com/sse

# .mcp.json
{
  "mcpServers": {
    "context7": {
      "type": "sse",
      "url": "https://mcp.context7.com/sse"
    }
  }
}

HTTP 방식으로 추가:

# 커맨드
claude mcp add --transport http context7 https://mcp.context7.com/sse

# .mcp.json
{
  "mcpServers": {
    "context7": {
      "type": "http",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    }
  }
}

자주 하는 실수:

❌ 잘못된 예
claude mcp add context7 npx -y @upstash/context7-mcp
→ "-y"가 claude mcp의 플래그로 해석될 수 있음

✅ 올바른 예
claude mcp add context7 -- npx -y @upstash/context7-mcp
→ "--" 뒤의 인자는 모두 MCP 서버 명령으로 전달

체크포인트

• [ ] claude mcp add 커맨드의 기본 문법을 작성할 수 있는가?
• [ ] .mcp.json 파일의 기본 구조(mcpServers, type, command, args)를 설명할 수 있는가?
• [ ] SSE 추가 시 --transport sse 플래그가 필요하다는 것을 아는가?
• [ ] stdio와 SSE/HTTP의 .mcp.json 구조 차이를 설명할 수 있는가?

11-3 MCP 전송 방식 비교 및 선택

한 줄 요약

stdio는 로컬에서 빠르게, SSE는 실시간 데이터 스트리밍용으로, HTTP는 일반적인 원격 API 연동용으로 사용하며, 가장 많이 쓰이는 방식은 stdio이다.

쉬운 설명 (배달 방식 비유)

"음식 배달에 비유하면: stdio는 집에서 직접 요리(로컬, 빠름), SSE는 뷔페 식당(한 번 연결하면 계속 음식이 나옴), HTTP는 배달앱 주문(필요할 때마다 주문-배달)이다."

핵심 포인트

실무 예제

상황별 올바른 선택:

Q: 로컬 파일 시스템을 읽고 쓰는 MCP 서버를 연결하고 싶다
A: ✅ stdio → 로컬 프로세스로 직접 실행, 네트워크 불필요

Q: 원격 서버에서 실시간 로그를 모니터링하고 싶다
A: ✅ SSE → 서버가 지속적으로 데이터를 밀어줌(Push)

Q: REST API를 제공하는 외부 서비스와 연동하고 싶다
A: ✅ HTTP → 일반적인 요청/응답 패턴

등록된 MCP 서버 확인:

> claude mcp list
tosspayments-integration-guide: npx -y @tosspayments/integration-guide-mcp@latest
context7: https://mcp.context7.com/sse (SSE)

선택 기준 정리

"어떤 전송 방식을 써야 할까?"

(1) 로컬 도구/스크립트 연동? → stdio (기본값, 가장 많이 사용)
(2) 원격 서버의 실시간 데이터? → SSE
(3) 일반적인 원격 API 연동? → HTTP
(4) 잘 모르겠으면? → stdio (기본값으로 시작)

체크포인트

• [ ] 세 가지 전송 방식의 이름과 특징을 각각 설명할 수 있는가?
• [ ] stdio가 가장 많이 사용되는 이유를 설명할 수 있는가?
• [ ] claude mcp list로 등록된 서버를 확인하는 방법을 아는가?
• [ ] 주어진 상황에 맞는 전송 방식을 선택할 수 있는가?

연습 문제

문제 1: MCP 개념 이해 (기본)

Q: MCP가 없는 상태에서 클로드에게 "우리 데이터베이스의 users 테이블 구조를 알려줘"라고 하면 어떻게 되는가? MCP가 있다면 어떻게 달라지는가?

문제 2: 서버 설정 실습 (중급)

Q: 다음 조건을 만족하는 .mcp.json 파일을 작성하라. - 서버 이름: my-db - 전송 방식: stdio - 실행 명령: npx - 인자: -y, @my-org/db-mcp-server - 환경 변수: DB_HOST를 localhost로 설정

{
  "mcpServers": {
    "my-db": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@my-org/db-mcp-server"
      ],
      "env": {
        "DB_HOST": "localhost"
      }
    }
  }
}

문제 3: 전송 방식 선택 (심화)

Q: 다음 세 가지 시나리오에서 각각 어떤 전송 방식을 선택해야 하는지, 그 이유와 함께 설명하라. 1. 로컬 파일을 분석하는 린트 도구를 MCP로 연결하고 싶다 2. SaaS 결제 서비스의 API 문서를 실시간으로 참조하고 싶다 3. CI/CD 파이프라인의 빌드 상태를 실시간으로 모니터링하고 싶다

문제 4: 트러블슈팅 (심화)

Q: claude mcp add 명령으로 MCP 서버를 추가했는데 claude mcp list에 표시되지 않는다. 원인과 해결 방법을 3가지 이상 제시하라.

부록 A: 용어 사전

부록 B: 비교표

B-1. MCP 전송 방식 3종 비교

B-2. MCP 서버 추가 방법 비교

B-3. MCP vs CLAUDE.md vs 커스텀 슬래시 커맨드 비교

부록 C: 참고 자료

• MCP 공식 사이트: https://modelcontextprotocol.io — MCP 프로토콜 공식 문서 및 스펙
• MCP GitHub: https://github.com/modelcontextprotocol — 프로토콜 구현체 및 SDK
• 책 유튜브 강의: https://bit.ly/3J4as96 — 11장 영상 강의
• 코드팩토리 GitHub: https://github.com/codefactory-co — 저자 예제 코드
• Context7 MCP: https://mcp.context7.com — 예제에 사용된 MCP 서버
• Anthropic MCP 블로그: https://www.anthropic.com/news/model-context-protocol — MCP 발표 포스트